---
title: SAIF.Business.Policy architecture
summary: Architectural responsibilities, boundaries, and interaction patterns.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-08-21
library: SAIF.Business.Policy
reference_type: package
---

# SAIF.Business.Policy architecture

`SAIF.Business.Policy` is a leaf-level domain/business component library for the policy domain within the `Claims.BOF.Web.LegalMaintenance` repository. It has no outbound project references, no UI, and no service host; it is consumed in this repository only through `SAIF.Business.View.Policy`, which is in turn consumed by the `LegalMaintenance` WebForms front end, `SAIF.Application.Claim.Legal`, and `SAIF.Business.Claim.Legal`.

## Responsibilities
- Provide the policy domain vocabulary — code⇄enum translation (`Enums`) and shared literal constants (`Constants`) used throughout the library.
- Declare integration contracts for the policy domain — `iPeriodRatingInfo`, `iPolicyPeriodBase`, `IPolicyHeaderDataProvider` (and the nested association contracts `IPolicyAssociationType`, `IPolicyAssociation`, `IPolicyHeaderAssociation`), and `CodeMaps/iAdjustedRateFactor` — implemented by consumers outside this library.
- Retrieve hazard-group reference data as read-only BOF business objects (`clsHazardGroup`, `clsHazardGroupCollection`) via the SAIF BOF data portal.
- Provide scalar policy facts (effective/expiration/anniversary dates, market type, premium-history set id, minimum premium, ownership system) through direct application-layer SQL and stored-procedure calls in `PolicyInformation`, bypassing the BOF business-object pattern.
- Maintain cached code-table lookups (`BenefitJurisdictions`, `ManualClassTypes`) via `CodeMaps` factory-backed `ExtendedCodeMap` subclasses.
- Expose a generated typed `DataSet` (`Institutions`) describing bank/financial-institution reference data (no in-library consumer found).*

## Component boundaries
- **Domain vocabulary layer** (`Enums.vb`, `Constants.vb`): pure, stateless code⇄enum translation and literal constants; depends on nothing, depended on by nearly everything else in the library.
- **Contract layer** (`iPeriodRatingInfo.vb`, `iPolicyPeriodBase.vb`, `IPolicyHeaderDataProvider.vb`, `CodeMaps/iAdjustedRateFactor.vb`): declaration-only interfaces plus one `MustInherit` class and two helper modules. Implementations live outside this library (e.g., `SAIF.Business.View.Policy/Associations/*`), making this the library's primary integration boundary with higher layers.*
- **BOF business-object layer** (`clsHazardGroup.vb`, `clsHazardGroupCollection.vb`): classic SAIF BOF pattern — business object + typed collection + nested `Criteria` implementing `IBusinessCriteria`, retrieved through the data portal with `BeforeRetrieve`/`AfterRetrieve` lifecycle hooks. Read-only by construction.
- **Application-layer data accessor** (`PolicyInformation.vb`): issues SQL/stored-procedure calls directly through `IPortalRequest`/`IDataRequest` for scalar policy facts — a second, parallel data-access style and the library's main technical-debt seam.*
- **Code-table map layer** (`CodeMaps/`): `ExtendedCodeMap` subclasses filled from a `SELECT` at construction, exposed through a partial `CodeMaps` factory class with static-variable caching.
- **Generated data-contract layer** (`Institutions` typed `DataSet`): bank/financial-institution reference schema; no code in this library consumes it.**

## Interaction model
- All database access is delegated: nothing in this library opens a connection or names a database. Every call takes an `IDataPortalInfo` supplied by the caller, and physical connection/environment resolution happens inside `SAIF.BOF.Framework`.*
- The library performs no threading, I/O, logging, HTTP calls, or configuration reads.
- Business objects are read-only projections (`AllowEdit=False`, `IsSavable=False`, all non-retrieve SQL properties throw), making this a query-side-only component.
- `SAIF.Business.View.Policy` is the sole in-repo consumer, implementing the policy-association contract family (`IPolicyAssociationType`, `IPolicyAssociation`, `IPolicyHeaderAssociation`, `StandardAssociationTypes`, `PolicyAssociationTypeCategories`) via `Associations/clsAssociationTypeCode.vb`, `clsPolicyAssociation.vb`, and `clsPolicyAssociationCollection`/`clsPolicyAssociationFactory.vb`. No in-repo consumer was found for `clsHazardGroup(Collection)`, `PolicyInformation`, `Enums`, `Constants`, `clsTranslationResult`, `CodeMaps`, `iPolicyPeriodBase`, `iPeriodRatingInfo`, `IPolicyHeaderDataProvider`, `iAdjustedRateFactor`, or `Institutions`.*
- Retrieval control flow for hazard groups (`GetHazardGroups`/`GetHazardGroupCollection`) delegates orchestration to `SAIF.BOF.Framework`'s data portal, which invokes `BeforeRetrieve`/`AfterRetrieve` lifecycle hooks on the collection to build and consume the SQL request.

## Architecture diagram
The following diagram shows the library's internal layering and its position relative to the consuming front end and the Oracle database.

```mermaid
flowchart TD
	A[Domain vocabulary layer<br>Enums, Constants] --> B[Contract layer<br>iPeriodRatingInfo, iPolicyPeriodBase,<br>IPolicyHeaderDataProvider, iAdjustedRateFactor]
	A --> C[BOF business-object layer<br>clsHazardGroup, clsHazardGroupCollection]
	A --> D[Application-layer data accessor<br>PolicyInformation]
	A --> E[Code-table map layer<br>CodeMaps]
	F[SAIF.Business.View.Policy] --> B
	F --> G[SAIF.Business.Policy]
	G --> C
	G --> D
	G --> E
	C --> H["SAIF.BOF.Framework data<br>portal"]
	D --> H
	H --> I[(Oracle database)]
	J["LegalMaintenance web front<br>end"] --> F
```

## Sequence diagram
The following diagram shows the hazard-group retrieval sequence (OP-01/OP-02), the library's primary BOF data-access flow.

```mermaid
sequenceDiagram
	participant Caller
	participant Collection as clsHazardGroupCollection
	participant Portal as SAIF.BOF.Framework data portal
	participant DB as Oracle database
	participant Item as clsHazardGroup
	Caller->>Collection: GetHazardGroups(dpi, effectiveDate)
	Collection->>Portal: RetrieveObject(Criteria)
	Portal->>Collection: BeforeRetrieve
	Collection->>Portal: assign RetrieveSQL, bind EffectiveDate
	Portal->>DB: execute request
	DB-->>Portal: result rows
	Portal->>Collection: AfterRetrieve
	loop each row
		Collection->>Item: New clsHazardGroup / Load(dpi, reader)
		Item-->>Collection: Add(child)
	end
	Collection-->>Caller: populated clsHazardGroupCollection
```

## Design constraints
- No outbound `<ProjectReference>` — the library sits at the bottom of the repository's local dependency graph.
- All external consumption is via NuGet packages/HintPath references declared in `packages.config`; no `<PackageReference>` elements are used.
- Read-only surface: hazard-group business objects and `PolicyInformation` accessors only support retrieval; create/update/delete SQL properties throw or are not implemented.
- No local exception handling around most scalar accessors — data-access exceptions from the framework propagate to the caller, except `PolicyMinimumPremium`, which swallows exceptions from `ProcessPortalRequest` in an empty `Catch`.*
- The target Oracle database/schema is never named in code or config; it is resolved at runtime by the caller-supplied `IDataPortalInfo`.

> **Note:** Statements marked with * were inferred from code structure, naming conventions, or
> contextual evidence where direct confirmation was not available in source artifacts. Statements
> marked with ** could not be confirmed; treat as unknown until verified.

## Related documentation
- [Index](index.md)
- [Overview](overview.md)
- [Dependencies](dependencies.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.md)
- [Database tables](database-tables.md)
- [SQL catalog](sql/index.md)
- [Procedures](procedures/index.md)
- [API reference](api/index.md)

## Sources
- `SAIF.Business.Policy/SAIF.Business.Policy.vbproj`
- `SAIF.Business.Policy/PolicyInformation.vb`
- `SAIF.Business.Policy/clsHazardGroup.vb`
- `SAIF.Business.Policy/clsHazardGroupCollection.vb`
- `SAIF.Business.Policy/CodeMaps/clsBenefitJurisdictionCodeMap.vb`
- `SAIF.Business.Policy/CodeMaps/clsManualClassTypeCodeMap.vb`